NewThread

NewThread
Header:	Threads.h		Carbon status:	Supported

Creates a new thread or allocates one from the existing pool of threads.

OSErr NewThread (
    ThreadStyle threadStyle, 
    ThreadEntryUPP threadEntry, 
    void *threadParam, 
    Size stackSize, 
    ThreadOptions options, 
    void **threadResult, 
    ThreadID *threadMade
);

threadStyle: The type of thread to create. Cooperative is the only type that you can specify. Historically, the Thread Manger supported two types of threads, preemptive and cooperative, but the Thread Manager no longer supports preemptive threads.
threadEntry: A pointer to the thread entry function.
threadParam: A pointer to a value that the Thread Manager passes as a parameter to the thread entry function. Specify NULL if you are passing no information.
stackSize: The stack size (in bytes) to allocate for this thread. This stack must be large enough to handle saved thread context, normal application stack usage, interrupt handling functions, and CPU exceptions. Specify a stack size of 0 (zero) to request the Thread Managerís default stack size.
options: Options that define characteristics of the new thread. See the ThreadOptions (page 3) data type for details on the options. You sum the options together to create a single options parameter.
threadResult: On return, a pointer to the address of a location to hold the function result provided by the DisposeThread function when the thread terminates. Specify NULL for this parameter if you are not interested in the function result.
threadMade: On return, a pointer to the thread ID of the newly created or allocated thread. If there is an error, threadMade points to a value of kNoThreadID.

function result: A result code. Δ

DISCUSSION

The NewThread function obtains a thread ID that you can use in other Thread Manager functions to identify the thread. If you want to allocate a thread from the pool of threads, specify the kUsePremadeThread option of the options parameter. Otherwise, NewThread creates a new thread.

When you request a thread from the existing pool, the Thread Manager allocates one that best fits your specified stack size. If you specify the kExactMatchThread option of the options parameter, the Thread Manager allocates a thread whose stack exactly matches your stack-size requirement or, if it canít allocate one because no such thread exists, it returns the threadTooManyReqsErr result code.

Before making any calls to NewThread, be certain that you first have called the Memory Manager function MaxApplZone to extend the application heap to its limit. You must call MaxApplZone from the main application thread before any other threads in your application run.

When you call the NewThread function, you pass, as the threadEntry parameter, a pointer to the name of the entry function to the thread. When the newly created thread runs initially, it begins by executing this function.

You can use the threadParam parameter to pass thread-specific information to a newly created or allocated thread. In the data structure pointed to by this parameter, you could place something like A5 information or the address of a window to update. You could also use this parameter to specify a place for a threadís local storage.

Be sure to create the storage for the threadResult parameter in a place that is guaranteed to be available when the thread terminatesófor example, in an application global variable or in a local variable of the applicationís main function (the main thread, by definition, cannot be disposed of so it is always available). Do not create the storage in a local variable of a subfunction that completes before the thread terminates or the storage will become invalid.

Do not pass a function descriptor as the threadEntry parameter to the NewThread function. For all Thread Manager functions that pass a function pointer, such as this one, you must pass the address of the function, not the address of a function descriptor. You are required to use function descriptors when you write code in the PowerPC instruction set that passes a functionís address to code that might be in the 680x0 instruction set. However, the threads in your application must all be in the same instruction setó 680x0 or PowerPC. Therefore, the function identified by the threadEntry parameter is by definition in the same instruction set as the NewThread function and a function descriptor is not required.

To dispose of a thread, use the DisposeThread function.

See the description of the ThreadOptions data type for details on the characteristics you can specify in the options parameter.

For more information about the thread entry function, see the ThreadEntryProcPtr function.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when ThreadsLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ThreadsLib 1.0 and later.